home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / dejagnu.lha / dejagnu-1.0.1 / tcl / doc / Fork.3 < prev    next >
Text File  |  1993-02-14  |  5KB  |  149 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_Fork tcl
  12. .BS
  13. .VS
  14. .SH NAME
  15. Tcl_Fork, Tcl_WaitPids, Tcl_DetachPids \- manage child processes
  16. .SH SYNOPSIS
  17. .nf
  18. \fB#include <tcl.h>\fR
  19. .sp
  20. int
  21. \fBTcl_Fork\fR( )
  22. .sp
  23. int
  24. \fBTcl_WaitPids\fR(\fInumPids, pidPtr, statusPtr\fR)
  25. .sp
  26. int
  27. \fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR)
  28. .SH ARGUMENTS
  29. .AS int *statusPtr
  30. .AP int numPids in
  31. Number of process ids contained in the array pointed to by \fIpidPtr\fR.
  32. .AP int *pidPtr in
  33. Address of array containing \fInumPids\fR process ids.
  34. .AP int *statusPtr out
  35. Address of place to store status returned by exited/suspended process.
  36. .BE
  37.  
  38. .SH DESCRIPTION
  39. .PP
  40. These procedures keep track of child processes in order to make it
  41. easier for one application to manage several children.
  42. If an application uses
  43. the UNIX \fIfork\fR and \fIwait\fR kernel calls directly,
  44. problems occur in situations like the following:
  45. .IP [1]
  46. One part of an application creates child C1.  It plans to
  47. let the child run in background, then later wait for it to
  48. complete.
  49. .IP [2]
  50. Some other part of the application creates another child C2,
  51. not knowing anything about C1.
  52. .IP [3]
  53. The second part of the application uses \fIwait\fR to wait for C2
  54. to complete.
  55. .IP [4]
  56. C1 completes before C2, so C1 is returned by the
  57. \fIwait\fR kernel call.
  58. .IP [5]
  59. The second part of the application doesn't recognize C1, so it
  60. ignores it and calls \fIwait\fR again.  This time C2
  61. completes.
  62. .IP [6]
  63. The first part of the application eventually decides to wait
  64. for its child to complete.  When it calls \fIwait\fR there are
  65. no children left, so \fIwait\fR returns an error and the
  66. application never gets to examine the exit status for C1.
  67. .PP
  68. The procedures \fBTcl_Fork\fR, \fBTcl_WaitPids\fR, and \fBTcl_DetachPids\fR
  69. get around this problem by keeping a table of child processes and
  70. their exit statuses.
  71. They also provide a more flexible waiting
  72. mechanism than the \fIwait\fR kernel call.
  73. Tcl-based applications should never call \fIfork\fR and
  74. \fIwait\fR directly;  they should use \fBTcl_Fork\fR,
  75. \fBTcl_WaitPids\fR, and \fBTcl_DetachPids\fR.
  76. .PP
  77. \fBTcl_Fork\fR calls \fIfork\fR and returns the result of
  78. the \fIfork\fR kernel call.
  79. If the \fIfork\fR call was successful then \fBTcl_Fork\fR also
  80. enters the new process into its internal table of child
  81. proceses.
  82. If \fIfork\fR returns an error then \fBTcl_Fork\fR returns that
  83. same error.
  84. .PP
  85. \fBTcl_WaitPids\fR calls \fIwait\fR repeatedly until one of the processes
  86. in the \fIpidPtr\fR array has exited or been killed or suspended by a
  87. signal.
  88. When this occurs, \fBTcl_WaitPids\fR returns the process
  89. identifier for the process and stores its wait status at
  90. \fI*statusPtr\fR.
  91. If the process no longer exists (it exited or was killed by a signal),
  92. then \fBTcl_WaitPids\fR removes its entry from the internal
  93. process table.
  94. If \fIwait\fR returns a process that isn't
  95. in the \fIpidPtr\fR array, \fBTcl_WaitPids\fR saves its wait
  96. status in the internal process table and calls \fIwait\fR again.
  97. If one of the processes in the \fIpidPtr\fR array has already
  98. exited (or suspended or been killed) when \fBTcl_WaitPids\fR
  99. is called, that process and its wait status are returned
  100. immediately without calling \fIwait\fR.
  101. .PP
  102. \fBTcl_WaitPids\fR provides two advantages.  First, it allows
  103. processes to exit in any order, and saves their wait statuses.
  104. Second, it allows waiting on a number of processes simultaneously,
  105. returning when any of the processes is returned by \fIwait\fR.
  106. .PP
  107. \fBTcl_DetachPids\fR is used to indicate that the application
  108. no longer cares about the processes given by the \fIpidPtr\fR
  109. array and will never use \fBTcl_WaitPids\fR to wait for them.
  110. This occurs, for example, if one or more children are to be
  111. executed in background and the parent doesn't care whether
  112. they complete successfully.
  113. When \fBTcl_DetachPids\fR is called, the internal process
  114. table entries for the processes are marked so that the
  115. entries will be removed as soon as the processes exit or
  116. are killed.
  117. .PP
  118. If none of the pids passed to \fBTcl_WaitPids\fR exists in
  119. the internal process table, then -1 is returned and \fIerrno\fR
  120. is set to ECHILD.
  121. If a \fIwait\fR kernel call returns an error,
  122. then \fBTcl_WaitPids\fR returns that same error.
  123. If a \fIwait\fR kernel call returns a process that isn't in
  124. the internal process table,  \fBTcl_WaitPids\fR panics and
  125. aborts the application.
  126. If this situation occurs, it means that a process has been
  127. created without calling \fBTcl_Fork\fR and that its exit
  128. status is about to be lost.
  129. .PP
  130. \fBTcl_WaitPids\fR defines wait statuses to have type \fIint\fR,
  131. which is correct for POSIX and many variants of UNIX. 
  132. Some BSD-based UNIX systems still use type \fIunion wait\fR for
  133. wait statuses;  it should be safe to cast a pointer to a
  134. \fIunion wait\fR structure to \fI(int *)\fR before passing
  135. it to \fBTcl_WaitPids\fR as in the following code:
  136. .nf
  137. .RS
  138.  
  139. \fBunion wait status;
  140. int pid1, pid2;
  141. \&...
  142. pid2 = Tcl_WaitPids(1, &pid1, (int *) &status);\fR
  143. .RE
  144. .fi
  145.  
  146. .SH KEYWORDS
  147. background, child, detach, fork, process, status, wait
  148. .VE
  149.